OpenAPI3.xでの仕様書の書き方 - swagger-merger対応

swagger-mergerに対応したOpenAPIの書き方をまとめます。

#OpenAPI

#Swagger

serina

2024.08.26

SBJソリューション部のserinaです。

前回、「OpenAPI3.xでの仕様書の書き方」という記事を書いたのですが、
swagger-mergerを使用することになりいざ実行してみたらallOfが使えない！！！

ということで、swagger-merger対応した書き方をまとめます。

バージョン

バージョン： OpenAPI 3.0.3
作成ファイル形式： yml
使用ツール：

swagger-ui
swagger merger

作成したパス構造

src/
│
├── paths/
│   └── index.yml
│
├── components
│   ├── examples/
│   │   └── index.yml
│   ├── parameters/
│   │   └── index.yml
│   ├── responses/
│   │   └── index.yml
│   ├── schemas/
│   │   └── index.yml
│   └── index.yml
│
└── index.yml

paths ... APIの定義ファイルを格納
components ... componentsの定義ファイルを格納
- examples ... 例の定義ファイルを格納
- parameters ... パラメータの定義ファイルを格納
- responses ... レスポンスの定義ファイルを格納
- schemas ... スキーマの定義ファイルを格納
index.yml ... 他のファイルを呼び出すメインファイル

書き方

allOfを使用せず$ref参照を使用する

Before

  responses:
    '500':
      allOf:
        - $ref: '../../responses/error-response.yml#/error_response_500'
      description: 500 Error

After

  responses:
    '500':
      description: 500 Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
          examples:
            default:
              $ref: '#/components/examples/error_response_500'

まず、Beforeの書き方をしても、descriptionは上書きされません。
descriptionや一部を上書きしたい場合は、responsesディレクトリを作成してそこにresponseを定義して呼び出す書き方はできないということになります。

そのため、Afterでは、schemasディレクトリにschemaを定義して上書きしない書き方に変更しています。

さらに、exampleはexampleだとうまく表示されないためexamplesにしてタイトルをdefaultなど任意の値にして、value以降を$ref参照で呼び出します。

exampleのファイルの書き方は、後述で説明しています。

ファイル分割したい場合はそれぞれのディレクトリにindexファイルを作成する

このようにパスを書いていたんですが、これだとうまく認識されません。

  responses:
    '500':
      allOf:
        - $ref: '../../responses/error-response.yml#/error_response_500'
      description: 500 Error

よって、先頭に # をつけた相対パスで記載するようにします。
ディレクトリごとにindexファイルを作成した書き方にします。

src/components/schemas/index.yml

user:
  $ref: './user.yml'

src/components/schemas/user.yml

type: object
properties:
  id:
    type: integer
  name:
    type: string

src/components/examples/index.yml

user_example:
  $ref: './user_example.yml'

src/components/examples/user_example.yml

value:
  id: 1
  name: John Doe

src/paths/index.yml

/users:
  $ref: './users.yml'

src/paths/users.yml

get:
  summary: Get users
  description: Retrieve a list of users.
  operationId: getUsers
  tags:
    - Users
  responses:
    '200':
      description: A list of users.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/user'
          examples:
            default:
              summary: Example user response
              value:
                - $ref: '#/components/examples/user_example'
    '500':
      description: 500 Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
          examples:
            default:
              $ref: '#/components/examples/error_response_500_example'